Summary

Hashed-key values are wrapped in an EVCacheValue envelope (key, value, flags, ttl, createTime) that is currently serialized with Java ObjectOutputStream, adding ~50–80 bytes of structural overhead per item. This adds a compact, length-prefixed binary format for the envelope while remaining fully backwards-compatible on reads.

This PR is two commits intended to be squashed at merge:

1. EVCacheValue: opt-in compact binary serde with backwards-compatible read — the wire format, transcoder dispatch, and the FP-gated rollout switch.
2. Route the EVCacheValue binary-serialization toggle through EVCacheTranscoderProperties — extracts the FP resolution into a typed bundle with a per-app → global → static-default chain.

What changed

• New EVCacheValueSerde class (com.netflix.evcache.pool) — public-final-non-instantiable codec, owns the wire format and all error handling:
  • static byte[] serialize(EVCacheValue) — length-prefixed binary layout: [magic 0x0C][reserved 0x00][int keyLen][key UTF-8][int valLen][value][int flags][long ttl][long createTime].
  • static EVCacheValue deserialize(byte[]) — bounds-checks length prefixes before allocating; on any corruption / unexpected exception warn-logs the failing field and a truncated hex dump (via Apache Commons Hex.encodeHexString, capped at 1024 bytes) and returns null. Matches BaseSerializingTranscoder's resilience contract (corruption → cache miss → caller refills from source of truth) so a single corrupt entry never crashes a get / getBulk / async pipeline.
  • static boolean isBinaryFormat(byte[]) — exposed for the dispatcher.
• EVCacheTranscoder becomes a thin dispatcher (no try/catch):
  • serialize: gates on properties.isBinarySerializationEnabled() && o instanceof EVCacheValue → EVCacheValueSerde.serialize; else super.serialize (Java).
  • deserialize: dispatches on EVCacheValueSerde.isBinaryFormat → EVCacheValueSerde.deserialize; else super.deserialize.
• EVCacheValue stays a pure POJO (codec moved out; constructor unchanged from pre-PR).
• EVCacheTranscoderProperties (new bundle in com.netflix.evcache.config) — typed access to the FPs that govern EVCacheTranscoder. Today it holds one entry (USE_BINARY_SERIALIZATION); the Key enum is the extension point for future transcoder properties. Resolution chain per property: per-app override → global default → static default, read once at construction and cached. A getProperty(Key, Class, default) escape hatch supports future dynamic reads without forcing every caller off the cached primitive.
• EVCacheImpl constructs an EVCacheTranscoderProperties for the envelope transcoder and injects it; max size is still read inline; compression stays pinned at Integer.MAX_VALUE so the leading magic byte is never gzip-rewritten.
• Reads auto-detect format by the leading byte (0xAC 0xED = legacy Java, 0x0C = binary), so a new client decodes existing cache entries unchanged.

Format-flag decision (reuse SERIALIZED + magic byte, not a fresh flag)

The binary envelope keeps the existing SERIALIZED flag and is disambiguated from Java by the leading byte, rather than allocating a new CachedData flag. Rationale:

• SERIALIZED semantically still means "serialized object → deserialize()"; the codec choice (Java vs binary) lives inside deserialize(). No flag constant is reassigned or repurposed, and decode() branch order is untouched.
• Consumers that route on SERIALIZED (e.g. the admin inspector, cache-warmer) keep working without a new flag constant to propagate.
• An old reader that hits binary bytes under SERIALIZED throws StreamCorruptedException (fails loud) rather than silently decoding garbage — which a fresh low-byte flag would cause (decodeString) on old readers.
• Invariant (documented in EVCacheValueSerde Javadoc): SERIALIZED payloads are self-describing by leading byte; a future third format must use a distinct non-colliding magic + the reserved version byte.

Reserved version byte

Byte index 1 of the binary payload is reserved (always 0x00 today). Reader read-and-ignores; not validated. Reason: forward-compat without an emergency reader rollout. If today's readers rejected any non-zero version, introducing a v2 in the future would require shipping reader support fleet-wide before any writer could emit a v2 byte, and a single misconfigured writer would crash all readers. By accepting any value today, future readers can branch on this byte to introduce breaking format changes backwards-compatibly.

Feature Property (rollout gate)

Resolved through EVCacheTranscoderProperties with a three-level fallback:

1. Per-app override: <appName>.binary.serialization.enabled
2. Global default: default.evcache.binary.serialization.enabled
3. Static default: false

• Read once at client construction and cached as a primitive on the (immutable) transcoder ⇒ deploy/restart required to take effect; this is NOT a live runtime toggle. Flip the property, then redeploy the consuming app.
• Default-off means production keeps writing Java; reads auto-detect both formats. Roll out reader-first: ship this change everywhere — including the admin inspector and cache-warmer — before enabling the FP for any writer.

Compatibility

• A client with this change decodes existing Java-serialized values unchanged (dual-format read).
• With the FP off (default), wire output is byte-identical to today.
• Corrupt binary payloads degrade to cache miss (null), matching the existing Java path. A single corrupt entry never crashes the caller.

Testing

EVCacheValueSerdeTest — 17 cases via the public EVCacheTranscoder.encode/decode API:

• Binary round-trip across edge cases (empty / unicode key / large 2 MB value / negative flags / zero ttl / negative & MAX createTime / MIN flags)
• Transcoder wire shape (binary flag on): SERIALIZED flag set, leading byte 0x0C, reserved byte 0x00
• Default transcoder (flag OFF) writes Java (0xAC 0xED) but reads both formats
• Backwards-compat: legacy ObjectOutputStream-serialized envelope still decodes
• Non-EVCacheValue passthrough (ArrayList stays on the Java path even with binary flag on)
• Size win: testBinaryIsSmallerThanJava asserts the binary envelope is strictly smaller than the Java one for a representative item
• Malformed binary: truncated, bogus oversize keyLen, negative keyLen all decode to null (logged with field + hex dump)
• Forward-compat: testDecodeBinaryWithOptionalAdditiveFieldIsForwardCompat — appends an unknown trailing field to a typical payload and asserts the reader still returns the typical envelope (cross-consistency check: if a real new field is added everywhere, the test continues to pass; if someone adds a non-additive field, this test fails).

EVCacheTranscoderPropertiesTest — 5 cases for the resolution chain: per-app wins, global fallback when per-app unset, static default when both unset, per-app beats global, null appName routes to global.

./gradlew :evcache-core:test green. Also smoke-tested end-to-end against a locally-published snapshot in a sample Spring Boot Netflix app — round-trip put/get/delete on hashed keys passed.

Chunked-payload integration is not covered by an automated test in this PR — chunking lives in EVCacheClient.createChunks/assembleChunks, which are content-opaque (byte copy + CRC + manifest) and require a live client to exercise. The binary format introduces no new chunking risk by construction: assembleChunks reassembles bytes byte-for-byte and CRC-checks them against the manifest before handing the result to the transcoder.

🤖 Generated with Claude Code